W05-1. Docker Compose - 강의 노트
5주차 강의 노트: Docker Compose 로 웹 + DB 한 번에
- Compose 가 왜 필요한지, 무엇을 대신해 주는지 안다.
compose.yaml의 기본 구조(services, ports, environment, volumes, depends_on, healthcheck)를 읽고 쓸 수 있다.docker compose up / ps / logs / exec / down으로 여러 컨테이너를 한 묶음으로 다룬다.- 비밀번호 같은 값을
.env파일로 분리한다.
진행: 이론 15분 (이 노트) → 실습 45분 (실습 가이드)
- Dockerfile 로 방명록 이미지
guestbook:v1,v2를 만들고 Docker Hub 에 올렸다 - 방명록은
DATABASE_URL이 없으면 메모리에 저장 → 컨테이너를 지우면 글이 사라졌다
1. 왜 Compose 인가
3주차에 웹 + DB 를 띄우려면 이렇게 해야 했습니다.
docker network create study-net
docker volume create study-pgdata
docker run -d --name study-db --network study-net -e POSTGRES_PASSWORD=... -v study-pgdata:/var/lib/postgresql postgres:18-alpine
# (DB 가 준비될 때까지 기다렸다가)
docker run -d --name study-web --network study-net -p 8080:8000 -e DATABASE_URL=... guestbook:v1
| 문제 | 설명 |
|---|---|
| 명령이 길고 많다 | 옵션 하나만 틀려도 동작하지 않음 |
| 순서가 중요하다 | 네트워크 → DB → (기다림) → 웹 |
| 기록이 남지 않는다 | 어떤 옵션으로 띄웠는지 나중에 알기 어려움, 다른 사람에게 전달하기 어려움 |
| 정리가 귀찮다 | 컨테이너, 네트워크, 볼륨을 하나하나 지워야 함 |
Compose 의 해결책: 이 모든 설정을 compose.yaml 파일 하나에 적고, 명령 한 줄로 올리고 내립니다.
flowchart TB
Y["📝 compose.yaml
(원하는 상태를 적은 파일)"] -- "docker compose up -d" --> R
subgraph R["Compose 가 알아서 만드는 것"]
N["네트워크
guestbook_default"]
V["볼륨
guestbook_db-data"]
W["web 컨테이너"]
D["db 컨테이너"]
end
R -- "docker compose down" --> X["한 번에 정리"]
docker run 은 어떻게 할지(How) 를 하나하나 명령하는 방식입니다.
compose.yaml 은 원하는 상태(What) 를 적어 두는 방식입니다. "웹 1개, DB 1개, 이렇게 연결" 이라고 적으면 Compose 가 그 상태를 만듭니다.
6주차 Kubernetes 도 이 선언형 방식을 씁니다. Compose 는 그 연습입니다.
2. YAML 문법 3분 정리
compose.yaml 과 Kubernetes 설정 파일은 모두 YAML 형식입니다.
# 주석은 # 으로 시작
이름: 값 # 키: 값 (콜론 뒤에 공백 필수)
목록:
- 첫 번째 # 목록은 "- " 로 시작
- 두 번째
묶음:
안쪽키: 값 # 들여쓰기로 소속을 표현 (보통 공백 2칸)
또다른키: 값
- 들여쓰기는 공백(스페이스)만 씁니다. 탭(Tab) 을 쓰면 에러가 납니다. VS Code 는 기본적으로 공백을 넣어 줍니다.
- 같은 수준의 항목은 들여쓰기 칸 수가 똑같아야 합니다.
키:값처럼 콜론 뒤에 공백이 없으면 안 됩니다.키: 값으로 씁니다."8080:8000"처럼 콜론이 들어간 값은 따옴표로 감쌉니다.
3. 오늘의 compose.yaml 읽기
services: # 띄울 컨테이너(서비스) 목록
web: # 서비스 이름 = 다른 컨테이너가 부를 때 쓰는 "주소"
build: . # 이 폴더의 Dockerfile 로 이미지 빌드
image: guestbook:compose # 빌드한 이미지에 붙일 이름
ports:
- "8080:8000" # = docker run -p 8080:8000
environment: # = docker run -e
APP_VERSION: v1-compose
DATABASE_URL: postgresql://guest:${DB_PASSWORD}@db:5432/guestbook
depends_on:
db:
condition: service_healthy # db 가 "healthy" 가 된 뒤에 web 시작
restart: unless-stopped # = docker run --restart unless-stopped
db:
image: postgres:18-alpine
environment:
POSTGRES_USER: guest
POSTGRES_PASSWORD: ${DB_PASSWORD} # .env 파일에서 값을 가져옴
POSTGRES_DB: guestbook
volumes:
- db-data:/var/lib/postgresql # = docker run -v (PostgreSQL 18 경로)
healthcheck: # "준비됐는지" 확인하는 방법
test: ["CMD-SHELL", "pg_isready -h localhost -U guest -d guestbook"]
interval: 5s
timeout: 3s
retries: 10
restart: unless-stopped
volumes:
db-data: # 위에서 쓴 볼륨을 여기서 선언
YAML 은 줄 뒤에 붙인
#도 주석입니다. Dockerfile 과 다르니 헷갈리지 마세요.
3-1. docker run 옵션과 1:1 대응
docker run |
compose.yaml |
|---|---|
--name study-web |
services: 아래의 이름 (web) |
-p 8080:8000 |
ports: - "8080:8000" |
-e 이름=값 |
environment: 이름: 값 |
-v 볼륨:/경로 |
volumes: - 볼륨:/경로 (+ 맨 아래 volumes: 선언) |
--network study-net |
자동 (프로젝트마다 네트워크를 하나 만들어 모두 연결) |
--restart unless-stopped |
restart: unless-stopped |
docker build -t ... |
build: . + image: ... |
3-2. 서비스 이름이 곧 주소
DATABASE_URL 의 @db:5432 를 보세요. db 는 서비스 이름입니다.
Compose 가 만든 네트워크에서는 3주차에 배운 Docker 내장 DNS 덕분에 서비스 이름으로 서로를 찾습니다.
3-3. depends_on + healthcheck: 기다렸다가 시작하기
| 설정 | 효과 |
|---|---|
depends_on: [db] (조건 없음) |
db 컨테이너가 시작되면 바로 web 시작. DB 가 아직 준비 중일 수 있음 |
depends_on: db: condition: service_healthy |
db 의 healthcheck 가 성공한 뒤에 web 시작 ✅ |
pg_isready -h localhost 인가 (검증하다가 찾은 함정)
PostgreSQL 은 첫 실행 때 초기화를 위해 잠깐 임시 서버를 띄웁니다. 이 임시 서버는 외부(TCP) 접속을 받지 않습니다.
-h localhost 를 붙이면 TCP 로 접속해 보고 판단하므로, 임시 서버를 "준비 완료" 로 착각하지 않습니다.
4. .env: 비밀번호를 파일 밖으로
compose.yaml 에 ${DB_PASSWORD} 라고 쓰면, Compose 가 같은 폴더의 .env 파일에서 값을 찾아 넣습니다.
# .env
DB_PASSWORD=guestpw
| 파일 | Git 에 올리나? | 이유 |
|---|---|---|
compose.yaml |
✅ | 구조(설계도)는 팀이 공유 |
.env |
❌ | 비밀번호 등 환경마다 다르고 민감한 값 |
.env 는 이미지에도 들어가면 안 됩니다
.dockerignore 에 .env 를 추가해서, 빌드할 때 이미지 안으로 들어갈 가능성을 막습니다. 실습에서 직접 추가합니다.
이것은 연습용 방법입니다. 실무의 비밀 관리는 9주차 Kubernetes Secret 과 10주차에서 다룹니다.
5. 주요 명령어
모든 명령은 compose.yaml 이 있는 폴더에서 실행합니다.
| 명령 | 하는 일 |
|---|---|
docker compose config |
파일 문법 검사 + .env 값이 채워진 최종 설정 보기 |
docker compose up -d |
전부 만들고 백그라운드로 실행 (이미 있으면 바뀐 것만 다시 만듦) |
docker compose up -d --build |
이미지를 다시 빌드한 뒤 실행 (코드를 고쳤을 때) |
docker compose ps |
이 프로젝트의 컨테이너 상태 |
docker compose logs [-f] [서비스] |
로그 보기 (서비스 이름을 주면 그것만) |
docker compose exec 서비스 명령 |
실행 중인 서비스 안에서 명령 실행 |
docker compose down |
컨테이너 + 네트워크 삭제. 볼륨(데이터)은 남김 |
docker compose down -v |
볼륨까지 삭제 (데이터 영구 삭제!) |
docker compose watch |
코드를 저장하면 자동으로 컨테이너에 반영 (개발용) |
이름 규칙
Compose 는 폴더 이름을 프로젝트 이름으로 씁니다. guestbook 폴더라면:
| 대상 | 이름 |
|---|---|
| 컨테이너 | guestbook-web-1, guestbook-db-1 (프로젝트-서비스-번호) |
| 네트워크 | guestbook_default |
| 볼륨 | guestbook_db-data |
6. Compose 의 한계 → Kubernetes 로
| Compose 로 충분한 것 | Compose 로 어려운 것 |
|---|---|
| 내 노트북에서 개발 환경 띄우기 | 서버 여러 대에 나눠 배포 |
| 테스트 환경, 소규모 서버 1대 | 서버가 죽으면 다른 서버에서 자동으로 다시 띄우기 |
| 팀원과 같은 환경 공유 | 트래픽에 따라 자동으로 늘리고 줄이기 |
| 같은 서비스 여러 개 앞에 로드밸런서 두기, 무중단 배포 |
docker compose up -d --scale web=3 으로 웹을 3개로 늘리면, 3개 모두 8080 포트를 쓰려다 충돌합니다.
"여러 개를 띄우고 그 앞에서 나눠 주는 일" 은 Kubernetes 의 Deployment + Service 가 해 줍니다(7~8주차).
핵심 요약
5주차 핵심
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
① Compose 여러 컨테이너 설정을 compose.yaml 하나에 "선언"
② 자동 처리 네트워크 자동 생성, 서비스 이름 = 주소 (web → db:5432)
③ 순서 보장 depends_on + condition: service_healthy + healthcheck
④ 비밀 분리 ${변수} ← .env 파일 (Git·이미지에 넣지 않기)
⑤ 명령 up -d [--build] / ps / logs -f / exec / down [-v]
⑥ 데이터 down 은 볼륨을 남기고, down -v 는 볼륨까지 지운다
⑦ 한계 서버 여러 대, 자동 복구, 오토스케일링 → Kubernetes
참고 자료
더 깊이 보고 싶다면 (볼트 내 정리 노트):
- 도커 개요2: WordPress + MariaDB Compose 예제
공식 문서:
- Compose file reference: https://docs.docker.com/reference/compose-file/
- Compose watch: https://docs.docker.com/compose/how-tos/file-watch/
- Compose 의 환경 변수(.env): https://docs.docker.com/compose/how-tos/environment-variables/variable-interpolation/